eslint-mdx

What is eslint-mdx?

The eslint-mdx package is an ESLint plugin that provides linting support for MDX (Markdown with JSX) files. It helps ensure code quality and consistency in MDX files by leveraging ESLint's capabilities.

What are eslint-mdx's main functionalities?

Linting MDX Files

This configuration allows ESLint to lint MDX files by extending the recommended settings provided by the eslint-mdx plugin.

module.exports = {
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended"]
    }
  ]
};

Custom MDX Rules

This configuration demonstrates how to add custom rules for MDX files. In this example, the rule 'mdx/no-jsx-html-comments' is set to 'error' to disallow HTML comments within JSX.

module.exports = {
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended"],
      "rules": {
        "mdx/no-jsx-html-comments": "error"
      }
    }
  ]
};

Integrating with Prettier

This configuration shows how to integrate Prettier with eslint-mdx to ensure consistent formatting in MDX files. The 'prettier/prettier' rule is configured to use the 'mdx' parser.

module.exports = {
  "overrides": [
    {
      "files": ["*.mdx"],
      "extends": ["plugin:mdx/recommended", "prettier"],
      "rules": {
        "prettier/prettier": ["error", { "parser": "mdx" }]
      }
    }
  ]
};

Other packages similar to eslint-mdx

eslint-plugin-markdown

eslint-plugin-markdown is an ESLint plugin that allows linting of JavaScript code blocks within Markdown files. Unlike eslint-mdx, which is specifically designed for MDX files, eslint-plugin-markdown focuses on JavaScript code within standard Markdown files.

remark-lint

remark-lint is a plugin for remark, a Markdown processor, that provides linting capabilities for Markdown files. While eslint-mdx leverages ESLint for linting MDX files, remark-lint is part of the remark ecosystem and focuses on Markdown linting with its own set of rules and plugins.

eslint-plugin-react

eslint-plugin-react is an ESLint plugin that provides linting rules for React applications. Although it is not specifically designed for MDX files, it can be used in conjunction with eslint-mdx to ensure React code within MDX files adheres to best practices.

README

ESLint Parser/Plugin for MDX, helps you lint all ES syntaxes. Linting code blocks can be enabled with mdx/code-blocks setting too! Work perfectly with eslint-plugin-import, eslint-plugin-prettier or any other eslint plugins. And also can be integrated with remark-lint plugins to lint markdown syntaxes.

TOC

• VSCode Extension
• Packages
• Install
• Notice
• Usage
  • Classic
  • Flat Config
• Parser Options
• Parser API
  • MDXCode
  • MDXHeading
  • Typings
• Rules
  • mdx/remark
• Prettier Integration
• Sponsors
• Backers
• Changelog
• License

VSCode Extension

VSCode MDX: Integrates with VSCode ESLint, syntaxes highlighting and error reporting.

Packages

This repository is a monorepo managed by changesets what means we actually publish several packages to npm from same codebase, including:

Package	Description	Version
eslint-mdx	ESLint Parser for MDX
eslint-plugin-mdx	ESLint Plugin, Configuration and Rules for MDX

Install

# yarn
yarn add -D eslint-plugin-mdx

# npm
npm i -D eslint-plugin-mdx

Notice

If you're using multi languages, js/jsx/ts/tsx/vue, etc for example, you'd better to always use overrides feature of ESLint, because configs may be overridden by following configs.

See #251 for more details.

Usage

Classic

.eslintrc file:

{
  "extends": ["plugin:mdx/recommended"],
  // optional, if you want to lint code blocks at the same time
  "settings": {
    "mdx/code-blocks": true,
    // optional, if you want to disable language mapper, set it to `false`
    // if you want to override the default language mapper inside, you can provide your own
    "mdx/language-mapper": {}
  }
}

Flat Config

eslint.config.js file:

import * as mdx from 'eslint-plugin-mdx'

export default [
  {
    ...mdx.flat,
    // optional, if you want to lint code blocks at the same
    processor: mdx.createRemarkProcessor({
      lintCodeBlocks: true,
      // optional, if you want to disable language mapper, set it to `false`
      // if you want to override the default language mapper inside, you can provide your own
      languageMapper: {},
    }),
  },
  {
    ...mdx.flatCodeBlocks,
    rules: {
      ...mdx.flatCodeBlocks.rules,
      // if you want to override some rules for code blocks
      'no-var': 'error',
      'prefer-const': 'error',
    },
  },
]

Then, make sure ESLint knows to run on .md or .mdx files:

eslint . --ext js,md,mdx

Parser Options

1. extensions (string | string[]): eslint-mdx will only resolve .mdx files by default, if you want to resolve other extensions as like .mdx, you can use this option.

2. markdownExtensions (string | string[]): eslint-mdx will only treat .md files as plain markdown by default, and will lint them via remark plugins. If you want to resolve other extensions as like .md, you can use this option.

3. ignoreRemarkConfig (boolean): Ignore the remark configuration defined in the project.

Parser API

MDXCode

A new MDXCode estree node type is exported from eslint-mdx which represents code blocks in mdx like the following:

<div>
  ```js
  export function foo() {
    return 'bar'
  }
  ```
</div>

See also https://github.com/syntax-tree/mdast#code

MDXHeading

A new MDXHeading estree node type is exported from eslint-mdx which represents markdown heading in mdx like the following:

<div>
# Here's a text gradient short code!
</div>

See also https://github.com/syntax-tree/mdast#heading

Typings

import type { BaseNode } from 'estree'
import type { JSXElement } from 'estree-jsx'

export interface MDXCode extends BaseNode {
  type: 'MDXCode'
  value: string
  lang?: string | null
  meta?: string | null
}

export type HeadingDepth = 1 | 2 | 3 | 4 | 5 | 6

export interface MDXHeading extends BaseNode {
  type: 'MDXHeading'
  depth: HeadingDepth
  children: JSXElement['children']
}

Rules

mdx/remark

possible fixable depends on your remark plugins:

Integration with remark-lint plugins, it will read remark's configuration automatically via unified-engine. But .remarkignore will not be respected, you should use .eslintignore instead.

If you want to disable or change severity of some related rules, it won't work by setting rules in eslint config like 'remark-lint-no-duplicate-headings': 0, you should change your remark config instead like following:

{
  "plugins": [
    "@1stg/remark-config",
    // change to error severity, notice `[]` is required
    ["lint-no-duplicate-headings", [2]],
    // disable following plugin
    [
      "lint-no-multiple-toplevel-headings",
      [0] // or false
    ]
  ]
}

Prettier Integration

If you're using remark-lint feature with Prettier both together, you can try remark-preset-prettier which helps you to turn off all rules that are unnecessary or might conflict with Prettier.

{
  "plugins": [
    "preset-lint-consistent",
    "preset-lint-recommended",
    "preset-lint-markdown-style-guide",
    "preset-prettier"
  ]
}

Sponsors

1stG	RxTS	UnTS

Backers

1stG	RxTS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

MIT © [e-mail]